Celestin Apprentice 5/Apprentice-Release5.iso/Source Code/C/Games/Xconq 7.1.0/src/xconq-7.1.0/doc/x11-sect.texi

Text File | 1996-07-07 | 16.6 KB | 495 lines | [TEXT/R*ch]

@node Introduction to X11 Xconq, Playing X11 Xconq, Playing Xconq, Playing Xconq

@section Introduction to X11 Xconq

@i{Xconq} includes an interface to the X Window System.  Since it is
only for version 11 of X, we will call it @i{X11 Xconq}.  The interface
is graphical, can work with either monochrome or color displays, and is
capable of opening multiple displays, one for each player, if desired.
It uses the Xt toolkit and Athena widgets.

@menu
* Installing X11 Xconq::
* Playing the Introductory Game with X11 Xconq::
@end menu

@node Installing X11 Xconq, Playing the Introductory Game with X11 Xconq, Introduction to X11 Xconq, Introduction to X11 Xconq

@subsection Installing X11 Xconq

The usual @samp{make} and @samp{make install} will generate and install
the executable and library into @file{usr/games/bin} and
@file{usr/games/lib/xconq}, respectively.  (See the file @file{INSTALL}
in the main source directory for more detailed instructions.)

The name of the executable is @file{xconq}.

@c need more when fonts used again

@c As with most X programs, you can customize @i{X11 Xconq} by using
@c resources.

@node Playing the Introductory Game with X11 Xconq, , Installing X11 Xconq, Introduction to X11 Xconq

@subsection Playing the Introductory Game with X11 Xconq

To begin an introductory game, give the command @samp{xconq -g intro}.

@node Playing X11 Xconq, Troubleshooting X11 Xconq, Introduction to X11 Xconq, Playing Xconq

@section Playing X11 Xconq

@menu
* Starting a New Game::
* Maps::
* Play::
@end menu

@node Starting a New Game, Maps, , Playing X11 Xconq

@subsection Starting a New Game

To play @i{X11 Xconq}, just type @samp{xconq}.  You will get the default
game, which has you and a single AI as the two opposing players, in a
randomly generated 60x30 area that is mostly unexplored.  The game
design in effect is called @samp{standard}.  It is a generic ``Empire''
type game, with cities, armies, airplanes, and ships of various types.

If you're new to @i{Xconq}, and find that @samp{standard} is too
complicated and/or confusing, try the introductory game @samp{intro}
instead; type @samp{xconq -g intro} to get it.  @samp{intro} is
generally like @samp{standard}, but it has fewer types of units and
terrain, you start with only one city, the one city is preset to build
armies, there is more land, and the other player starts closer.  Note
that some of these changes mean that luck plays a larger role in
determining whether you win or lose; so if you find yourself losing, it
may only be because your starting position was poor.  Success in the
standard game, however, depends almost entirely on skill, so play it
when you're more experienced with @i{Xconq}.

By default, the X11 interface opens up windows on the display named in
the environment variable @code{DISPLAY}, and connects it with the first
side and player in the game.

@menu
* Xconq Command Options::
* New Game Dialogs::
@end menu

@node Xconq Command Options, New Game Dialogs, Starting a New Game, Starting a New Game

@subsubsection Xconq Command Options

The arguments to an @i{Xconq} command consist of a list of player specifications
and possibly some additional options.

@table @code

@item [@var{name}][,@var{ai}][/@var{config}][@@@var{display}][+@var{adv}]
Attempt to open a display on @var{display} and assign a player/side to it.
Options include naming the player @var{name}, adding an AI of type
@var{ai}, using the side config file @i{config}
and asking for an advantage of @var{adv}.
@var{adv} defaults to 1.
If @var{name} is not supplied, then @var{name}
is assumed to be the display name.
A display named just @code{"_"} is equivalent to the default display,
as in the value of the environment variable @code{DISPLAY}.

@end table

You can get a variety of uses out of player specs.  For instance,
the player spec @code{,ai+4} asks for an AI, of a default type
appropriate to its side, with a starting advantage of 4.
If you want to give yourself an advantage, just specify @code{+4}
anywhere on the command line.

The following options are always available:

@table @code

@item -c @var{n}
Write a checkpoint every @var{n} turns.

@item -design
Make every side in the game be a designer.

@item -e[,@var{ai}][+@var{adv}] @var{n}
Create @var{n} sides and AIs to play them, using the optional @var{ai}
and @var{adv} to set the AI type and advantage of each.

@item -f @var{filename}
Play the game found in @var{filename}.

@item -g @var{gamename}
Play the game @var{gamename}, if one by that
name exists in the library (the default, or
the location specified with @code{-L}.

@item -h @var{n}
Wait for @var{n} human players to join.
[not yet implemented]

@item -help, --help
List all of the options.
If a game was loaded using @code{-g} or @code{-f},
also list all of the variants for the game.

@item -join
Connect to a game named \fIgame\fP.
[not yet implemented]

@item -L @var{directory}
Search in @var{directory} for game modules.

@item -mail
Arrange to run the game as play-by-email.
If you use this option, each player must be given both a name
and host, in the form of an Internet address.
[not yet implemented]

@item -r
Do not add a player on a local display.
If you use this, you must list every player on the
command line explicitly.

@item -w
Suppress warnings.

@item -wait
[not yet implemented]

@item --version
Display version information.

@item -x
Bring up a set of new game, variant, and player setup dialogs.

@end table

The following options only work if the game allows for the
corresponding variants:

@table @code

@item -M @var{width}[x@var{height}][W@var{circumf}][+@var{lat}][+@var{lon}]
Set the size and position of the game area If only @var{width} is given,
then the @var{height} defaults to the same as @var{width}.
Circumference defaults to 360, @var{lat} and @var{lon} default to 0.
The name of the variant is @code{world-size}.

@item -sq
Set sides to move in sequence, one at a time.
The variant is @code{sequential}, with a value of 1.

@item -sm
Set sides to all move simultaneously.
The variant is @code{sequential}, with a value of 0.

@item -t
Set realtime variants.

@item -v
Set the world to have been seen already.
The variant is @code{world-seen}, with a value of 1.

@item -V
Set everything to be seen all the time.
The variant is @code{see-all}, with a value of 1 (@code{true}).
If @code{see-all} defaults to being true for a game,
then you can make it false by using @code{-vsee-all=false}
or @code{-vsee-all=0}.

@item -v[@var{name}][=@var{value}]
Set the variant named @var{name} to have the value @var{value}.  If the
@var{value} is not supplied, it defaults to 1 (@code{true}).

@item -vhelp
Display variant help info.
This lists the available variants as @code{-help} does.

@end table

If debugging has been compiled in, then the options @code{-D}
and @code{-R} are also available.
See the hacking chapter of the manual for more detail.

The following options apply only to the default X11 display:

@table @code

@item -bg @var{color}

@item -display @var{displayname}

@item -fg @var{color}

@item -geometry @var{geometry}

@item -name @var{name}

@end table


@node New Game Dialogs,  , Xconq Command Options, Starting a New Game

@subsubsection New Game Dialogs

If you give the command line option @code{-x}, @i{Xconq} will
display a series of dialogs that you can use to set up a game
interactively.

@node Maps, Play, Starting a New Game, Playing X11 Xconq

@subsection Maps

Once the game has started, you have at least one ``map window'' open.
(For brevity, these can be called just ``maps'').
Each map window has identical capabilities, so you can play by using
just one, or have one for each area of interest, or have some of them serve
specialized purposes.
For instance, you can have a map window that shows the entire world.

@menu
* Map Parts::
* Scrolling Maps::
* View Control Popup::
@end menu

@node Map Parts, Scrolling Maps, Maps, Maps

@subsubsection Map Parts

Each map window consists of a number of panes, whose size you may
adjust by dragging the small square grips that may be seen on the
the pane boundaries.

@example
----------------------------------------------------------
|                                     |                  |
|           history/notices           |                  |
|                                     |                  |
|-------------------------------------|     sides        |
|           command prompt            |                  |
|-------------------------------------|                  |
|             turn/date               |------------------|
|-------------------------------------|                  |
|       |                             |                  |
|       |      unit/cell info         |                  |
|       |                             |                  |
|       |-----------------------------|                  |
|       |                             |    unit types    |
|       |                             |                  |
| ctrl  |                             |                  |
| panel |                             |                  |
|       |                             |                  |
|       |         map view            |                  |
|       |                             |                  |
|       |                             |------------------|
|       |                             |                  |
|       |                             |                  |
|       |                             |     panner       |
|       |                             |                  |
|       |                             |                  |
----------------------------------------------------------
@end example
@c should prevent break across pages here

The map view is the actual display of the world.

Each map may have one @i{current position} and one @i{current unit}.
The current position is specially highlighted, and the info subwindow
displays information about it.  If in addition there is a current
unit at the current position, then it will be highlighted rather
than the entire cell, and the info pane will describe it
in detail.

The info pane has the general form
@example
<unit owner, type, name>       <hp> <acp>|<cp> <cxp>
<location>
<occupants>                    <supply>
<plan>                         <more supply>
<tasks>
@end example
Items like @code{<hp>} and @code{acp} have the form
@code{@var{current}/@var{max}}, so that you can get an idea
of how the value compares to what it could be.

@node Scrolling Maps, View Control Popup, Map Parts, Maps

@subsubsection Scrolling Maps

It will nearly always be the case that the world is too large to be seen
all at once.  You can scroll around in two ways.  First, if you are in
survey mode, and click near any edge of the view, @i{Xconq} will put the
position you clicked at the center of the view.  By clicking in the same
place repeatedly, you can ``walk'' the view in any desired direction.

If you want to go directly to a particular part of the world, use the
panner in the bottom right corner of the map window.  To use the panner,
click and drag the shadowed box inside the panner.  The panner is sized
to match the map, and the shadowed box is sized to match the view, so
you can get a general idea of of where the map is within the world.

@node View Control Popup,  , Scrolling Maps, Maps

@subsubsection View Control Popup

If you click the button labelled ``More...'' in the leftside controls,
you will get a popup dialog that is a full set of viewing controls.
Unlike the leftside view controls, these do not act at once; instead,
you toggle them on or off, then click on ``Apply'' or ``Done'' to see
the effects.  This allows you to make a number of changes, but only
redraw the map once when you are ready to see the results.  ``Apply''
leaves the popup in place, while ``Done'' makes it go away.  You can
leave the popup up permanently and continue play, if you like.

Note that each map will have its own separate view control popup, and
that they're not clearly distinguished from each other.  Fortunately,
these only affect display, not the game itself.

@node Play,  , Maps, Playing X11 Xconq

@subsection Play

The basic idea of play is to be in move mode, let the program select the
next unit to do something, then give it a command, either by clicking
the mouse or by typing on the keyboard.

Each map may be in either survey or move mode (@xref{Modes})
independently of the others.  In survey mode, the default actions are
not to do anything, while in move mode, the default actions are to do
things.  This principle applies to both mouse and keyboard commands.
For instance, 'h' in survey mode moves the current position west by one
cell, but in move mode it causes the current unit to try to move west by
one cell.

@menu
* Using the Mouse::
* Using the Keyboard::
* Saving and Restoring Games::
@end menu

@node Using the Mouse, Using the Keyboard, Play, Play

@subsubsection Using the Mouse, excuse me, Pointer

Although in classic X style, all the actions may be arbitrarily
rebound, for simplicity the default @i{Xconq} setup uses the
left button for the most important actions.

@node Using the Keyboard, Saving and Restoring Games, Using the Mouse, Play

@subsubsection Using the Keyboard

The general commands (@xref{Standard Keyboard Commands}) all work.

Commands that operate on units will be applied to the current unit
of the map.  If the map has no current unit, then you will get an error message.

Commands that need further input will generally request it from
the prompt subwindow that is sandwiched between the history subwindow
and the date subwindow.  You do not need to put the cursor over
the prompt window to type into it however; when a prompt is up,
any typed characters will be considered to be part of the answer
to the prompt.
You can type in an escape (@samp{C-[}) character to cancel the
command and clear the prompt.

If the request is for a unit type, such as when choosing a type
to construct,
you can choose the type either by typing its character,
or by clicking on its entry in the unit type list.

The X11 interface defines these additional commands.

@table @code

@item @code{ v }
(@code{flash}).  Highlight the position of the current unit.

@item @code{ @{ }
(@code{z-in}) Zoom in (cells appear larger).

@item @code{ @} }
(@code{z-out}) Zoom out (cells appear smaller).

@end table

@table @code

@item @code{close}
Close a map window.

@item @code{map}
Open a new map window.

@item @code{rv}
Switch to reverse video.

@item @code{orders}
Popup a dialog for setting standing orders.

@item @code{side}
Open a closeup of the side.

@item @code{unit}
Open a closeup of the current unit.

@item @code{world-map}
Open a world map window.
@ifset FULL
This is like @code{map}, but the map is scaled to show the whole world
at once.
@end ifset

@item @code{mono}
Switch to monochrome display. (debugging)
@ifset FULL
This is really meant for debugging only,
and is only available if debugging was compiled in.
@end ifset

@end table

@node Saving and Restoring Games,  , Using the Keyboard, Play

@subsubsection Saving and Restoring Games

The save command @samp{S} saves games to @samp{save.xconq}.  The saved
game is a normal text file.  To restore the game, give the command
@samp{xconq -f save.xconq}.  The saved game preserves all of the
player information, including display names, so the restored game
will use all of the same displays as before.

You can change which displays go with which sides by using @code{-r}
to suppress the addition of a default player, and listing all of the
players explicitly, in the order desired.  For instance, suppose that
the original 5-player game was started with the arguments
@code{foo:0.0 joe@@bar:0.0 -e 2}, then to just change the displays,
restore with
@code{-f save.xconq -r baz:0.0 weeble:0.0 joe@@andros:0.0}.
This puts the original person who started the game onto @code{baz:0.0},
and the other two humans on @code{weeble:0.0} and @code{andros:0.0},
while leaving the two AIs unaffected.

This ability is also useful for swapping sides, although it can be
tricky to get right.  For instance,
@code{-f save.xconq -r ,ai ,ai ,ai ,@@foo:0.0 joe,@@bar:0.0}
restores the game, but gives the first three sides to the default
AI, and the last two (which had been played by AIs) to humans, and
disables the AIs that had been running them.  (The @code{,@@} sequence
effectively asks for an AI with an empty type name, which is interpreted
to mean ``no AI''; otherwise the displays would have been opened, with
an AI moving the units.)

@node Troubleshooting X11 Xconq, , Playing X11 Xconq, Playing Xconq

@section Troubleshooting X11 Xconq

By far the most common problem with the X11 interface is setting up a
game with multiple displays.  Future versions of @i{Xconq} will allow
for players to come in at their leisure, but for now every display must
be specified during startup.